{\rtf1\ansi\ansicpg1252\deff0\deflang16393\deflangfe16393\deftab420{\fonttbl{\f0\froman\fprq2\fcharset0 Times New Roman;}{\f1\fswiss\fprq2\fcharset0 Arial;}{\f2\froman\fprq2\fcharset2 Symbol;}{\f3\fswiss\fprq2\fcharset0 Calibri;}{\f4\fmodern\fprq1\fcharset0 Courier New;}{\f5\fswiss\fprq2\fcharset0 Arial Narrow;}{\f6\fnil\fprq2\fcharset2 Wingdings;}{\f7\fnil\fprq2\fcharset0 Wingdings;}}
{\colortbl ;\red255\green0\blue0;\red23\green54\blue93;\red0\green0\blue0;\red0\green0\blue255;\red0\green176\blue80;\red51\green51\blue153;\red166\green166\blue166;}
{\*\generator Msftedit 5.41.21.2509;}\viewkind4\uc1\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx720\ul\b\f0\fs32 DST Capacity Tools XSeries Report Services Component Specification\par
\pard\nowidctlpar\sa120\ulnone\b0\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx360\b\f1\fs24 1.\tab Design\f0\fs20\par
\pard\nowidctlpar\li720\b0\f1 The IBM Development Server Team (DST) provides operational support and infrastructure to IBM practitioners that support both IBM internal and commercial accounts. DST infrastructure and support offerings are innovative in that they provide low cost, quick-turnaround, flexible HW/SW infrastructure that far surpasses any other non-production hosting environment in IBM. DST offerings are reserved to any IBM practitioner or project that requires a development, test or other non-production environment.\par
\par
DST has a variety of traditional and non-traditional offerings that require the DST support personnel to support an infrastructure that spans the globe. As time has passed, the number of servers and a richer set of offerings have grown exponentially and the need for a set of more sophisticated tools to monitor infrastructure capacity has become a high priority. The primary reasons to gather data and report on infrastructure are to:\par
\par
\pard\nowidctlpar\fi-360\li1440\f2\'b7\tab\f1 Empower the DST Operational Support team with relevant capacity information to ensure that DST infrastructure is meeting HW and network resource demand\par
\pard\nowidctlpar\li720\par
\pard\nowidctlpar\fi-360\li1440\f2\'b7\tab\f1 Provide insight for the needs for future Capital Requests and when they might be needed\par
\pard\nowidctlpar\li720\par
This component provides the XSeries report service.\par
\par
\ul\b Design Approach:\par
\pard\nowidctlpar\ulnone\b0\par
\pard\nowidctlpar\li720 This component defines mainly the XSeriesReportService and its default implementation. \par
\par
The design provides the implementation class of the XSeriesReportService as POJO class with setter API to configure them. This is needed so that the component which is supposed to work in Spring framework can be wired using Spring configuration file.\par
\par
\b The setter methods in the service implementation class do not perform any argument check or throw IllegalArgumentException. There is a method called validateConfiguration() in the service implementation class which performs check on all the configuration data and throws ConfigurationException if any of the configuration issues found. This method has been annotated with @PostConstruct so that the Spring framework invokes this method after the bean configuration of the service implementation is done.\par
\par
The service implementation class call the validateConfiguration() method in each of its service methods prior to executing the service method logic. This ensures that the service implementation class works well outside the Spring environment as well and report any configuration issues.\par
\par
\cf1\ul XML Parsing and XML Writing:\par
\par
\ulnone\b0 As required by the RS [section for technical constraints lists this], the parsing of the XML input for XSeries Capacity Data for import of capacity data is done using the JAXP SAX Parser.\par
\par
The writing of XML for the XSeries Summary Report and XSeries Detail Report is done through \b simple String writing of the XML data over creating XML DOM and writing the DOM. \b0 This is primarily done for 3 points:\par
\pard\nowidctlpar\fi-360\li1080 a.\tab The report data can be fairly large and hence having a 2 steps, one creating the DOM structure from the data and then transforming the data will give lesser performance to writing the data as String.\par
b.\tab Since the report data can be large, creating a DOM with the entire report data would require good amount of memory and as data grows, could lead to OutOfMemory cases. With simple string writing, we write out the data to the output stream as we process the data.\par
c.\tab The XML structure for the report is fairly simple as defined in the later sections in the document.\par
\pard\nowidctlpar\sa120\cf0\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b\f1 1.1\tab Design Patterns \par
\pard\nowidctlpar\li701\sa120\ul\b0 Strategy pattern:\ulnone  Strategy pattern is followed by XSeriesReportServiceImpl using AuditService, LookupDataService as a Strategy. XSeriesReportServiceImpl is the context, AuditService and LookupDataService the strategy interfaces and the concrete strategy implementation being injected into the XSeriesReportServiceImpl through the Spring framework.\par
\par
\ul IOC pattern:\ulnone  IOC pattern is followed in this component by allowing the XSeriesReportServiceImpl to be configured by Spring IOC mechanism.\f0\par
\b\par
\ul\b0\f1 DAO/DTO pattern:\ulnone  XSeriesReportServiceImpl acts like a data access interface for the DAO XSeriesCapacity entity by allowing persistence of these entities and their retrieval for report purpose. Also DTO entities of XSeriesSummaryReportEntry are used for transferring the report data across layers.\b\f0\par
\pard\nowidctlpar\sa120\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\f1 1.2\tab Industry Standards \par
\pard\nowidctlpar\li720\sa120\sl240\slmult0\b0 JPA\par
Spring IOC\par
CSV\par
XML, XSD\par
JAXP, SAX\par
\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b\f1 1.3\tab Required Algorithms\par
\pard\nowidctlpar\li720\cf1\ul Note:\cf0\ulnone\b0\f3\fs22  All other algorithms have been provided in detail in the implementation notes in the method docs, please refer for the same for details.\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\i\f1\fs20 1.3.1\f0\tab\f1 Logging \f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4 Note: Logging needs to be performed in XSeriesReportServiceImpl classes only if the logger instance in it is not null.\par
1. Logging is performed using Log 4j in each of the service classes implementation provided in this component and also in the controller provided in the component.\par
2. Each exception will be logged at ERROR level. There will be logging of method entry/exit and parameter input/output at the DEBUG level for each of the service methods. \par
\cf1\ul\b\f1 Note:\cf0\ulnone\b0\f3\fs22  The implementation notes in the method docs do not mention of the logging to be done. This has been done so that the focus the core implementation logic is maintained in the method docs. Nevertheless the logging as mentioned in this point needs to be done in all the service methods of the service class.\f0\par
\cf2\f4\fs20 3. The logging of input/output information requires detailed printing of entity data. All entities provide a JSON version of their data, to be supplied in a toJSONString():String method and this needs to be used for printing entity data.\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.2\f0\tab\f1 CSV Format for XSeries Summary Report\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
1. The first line in the CSV file is for the header data which would be as follows:\par
\ldblquote Hosting Environment\rdblquote  , \rdblquote Hosting Class\rdblquote  , \rdblquote Data Center Site\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Total\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Used\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Free\rdblquote , \ldblquote VMWare Stats-Memory(GB)-Total\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Used\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Free\rdblquote  ,  "Measured Statistics-Processing Power(GHz)-Average" , "Measured Statistics-Processing Power(GHz)-High" , "Measured Statistics-Processing Power(GHz)-Low" , "Measured Statistics-Memory(GB)-Average" , "Measured Statistics-Memory(GB)-High" , "Measured Statistics-Memory(GB)-Low" , "Date"\par
\par
2. The second as the rest of the lines will contain the corresponding data for these separated by comma and each of the data element will be contained in double quotes. [example: \ldblquote Host1\rdblquote ]\par
\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.3\f0\tab\f1 CSV Format for XSeries Detail Report\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
1. The first line in the CSV file is for the header data which would be as follows:\par
\ldblquote Site\rdblquote  , \rdblquote Host Name\rdblquote  , \rdblquote Hypervisor version\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Total\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Used\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Free\rdblquote , \ldblquote VMWare Stats-Memory(GB)-Total\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Used\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Free\rdblquote  ,  "Measured Statistics-Processing Power(GHz)-Average" , "Measured Statistics-Processing Power(GHz)-High" , "Measured Statistics-Processing Power(GHz)-Low" , "Measured Statistics-Memory(GB)-Average" , "Measured Statistics-Memory(GB)-High" , "Measured Statistics-Memory(GB)-Low"\par
2. The second as the rest of the lines will contain the corresponding data for these separated by comma and each of the data element will be contained in double quotes. [example: \ldblquote Host1\rdblquote ].\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.4\f0\tab\f1 CSV Format for import of XSeries Capacity Data\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
1. The first line in the CSV file is for the header data which would be as follows:\par
"Hosting Environment" , "Data Center Site" , \ldblquote Hosting Class\rdblquote  , \rdblquote Host Name\rdblquote  , \rdblquote Hypervisor version\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Total\rdblquote  , \ldblquote VMWare Stats-Processing Power(GHz)-Used\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Total\rdblquote  , \ldblquote VMWare Stats-Memory(GB)-Used\rdblquote  , "Measured Statistics-Processing Power(GHz)-Average" , "Measured Statistics-Processing Power(GHz)-High" , "Measured Statistics-Processing Power(GHz)-Low" , "Measured Statistics-Memory(GB)-Average" , "Measured Statistics-Memory(GB)-High" , "Measured Statistics-Memory(GB)-Low"\par
2. The second as the rest of the lines will contain the corresponding data for these separated by comma and each of the data element will be contained in double quotes. [example: \ldblquote Host1\rdblquote ].\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.5\f0\tab\f1 XML Format for XSeries Summary Report\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
The schema definition in XSD for the format of the XML that would be generated as a part of the XSeries Summary Report is as follows:\par
\f5\fs16 <?xml version="1.0"?>\par
<xs:schema id="XSeriesSummaryReport" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/NewXMLSchema" xmlns:tns="http://www.example.org/NewXMLSchema" elementFormDefault="qualified">\par
  <xs:element name="XSeriesSummaryReport">\par
    <xs:complexType>\par
      <xs:choice minOccurs="0" maxOccurs="unbounded">\par
        <xs:element name="XSeriesSummaryReportEntry">\par
          <xs:complexType>\par
            <xs:sequence>\par
              <xs:element name="Hosting-Environment" type="xs:string" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Hosting-Class" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Data-Center-Site" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Processing-Power-Free" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Free" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Date" type="xs:date" minOccurs="1" maxOccurs="1" />\tab\tab\tab   \par
            </xs:sequence>\par
          </xs:complexType>\par
        </xs:element>\par
      </xs:choice>\par
    </xs:complexType>\par
  </xs:element>\par
</xs:schema>\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.6\f0\tab\f1 XML Format for XSeries Detail Report\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
The schema definition in XSD for the format of the XML that would be generated as a part of the XSeries Detail Report is as follows:\par
\f5\fs16 <?xml version="1.0"?>\par
<xs:schema id="XSeriesDetailReport" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/NewXMLSchema" xmlns:tns="http://www.example.org/NewXMLSchema" elementFormDefault="qualified">\par
  <xs:element name="XSeriesDetailReport">\par
    <xs:complexType>\par
      <xs:choice minOccurs="0" maxOccurs="unbounded">\par
        <xs:element name="XSeriesDetailReportEntry">\par
          <xs:complexType>\par
            <xs:sequence>\par
              <xs:element name="Site" type="xs:string" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Host-Name" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Hypervisor-Version" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Processing-Power-Free" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Free" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
            </xs:sequence>\par
          </xs:complexType>\par
        </xs:element>\par
      </xs:choice>\par
    </xs:complexType>\par
  </xs:element>\par
</xs:schema>\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\i\f1 1.3.7\f0\tab\f1 XML Format for import of XSeries Capacity Data\f0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\sa120\sl240\slmult0\cf2\i0\f4\par
The schema definition in XSD for the format of the XML in which the XSeries Capacity Data would be imported is as follows:\par
\f5\fs16 <?xml version="1.0"?>\par
<xs:schema id="XSeriesCapacityData" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.example.org/NewXMLSchema" xmlns:tns="http://www.example.org/NewXMLSchema" elementFormDefault="qualified">\par
  <xs:element name="XSeriesCapacityData">\par
    <xs:complexType>\par
      <xs:choice minOccurs="0" maxOccurs="unbounded">\par
        <xs:element name="XSeriesCapacityDataEntry">\par
          <xs:complexType>\par
            <xs:sequence>\par
              <xs:element name="Hosting-Environment" type="xs:string" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Data-Center-Site" type="xs:string" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Hosting-Class" type="xs:string" minOccurs="1" maxOccurs="1" />\tab\tab\tab   \par
              <xs:element name="Host-Name" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="Hypervisor-Version" type="xs:string"  minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
              <xs:element name="VMWare-Stats-Processing-Power-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Total" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="VMWare-Stats-Memory-Used" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Processing-Power-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Average" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-High" type="xs:float" minOccurs="1" maxOccurs="1" />\par
\tab\tab\tab   <xs:element name="Measured-Statistics-Memory-Low" type="xs:float" minOccurs="1" maxOccurs="1" />\par
            </xs:sequence>\par
          </xs:complexType>\par
        </xs:element>\par
      </xs:choice>\par
    </xs:complexType>\par
  </xs:element>\par
</xs:schema>\cell\row\pard\nowidctlpar\sa120\sl240\slmult0\cf3\f0\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\cf0\b\f1 1.4\tab Component Class Overview\f0\par
\pard\nowidctlpar\li720\sa120\f1 XSeriesReportService \b0 [interface]: \par
XSeriesReportService is the main interface of this component and provides service methods for generating xseries reports and handling data for xseries report. It provides methods for fetching the report contents for the xseries summary and detail report and also provides methods for persisting these report contents in either XML or CSV format. It also provides methods to import xseries capacity data from XML or CSV file and also ability to store xseries capacity data into persistence.\par
Thread-Safety: The implementation of this interface are expected to be thread-safe during the servicing of the service methods, once the initialization and configuration of the service class is done and the configuration values in the service class are not mutated during the servicing of the service methods.\par
\par
\b XSeriesReportServiceImpl \b0 [class]: \par
XSeriesReportServiceImpl is the default implementation of XSeriesReportService provided in this component. It provides service methods for generating xseries reports and handling data for xseries report. It provides methods for fetching the report contents for the xseries summary and detail report and also provides methods for persisting these report contents in either XML or CSV format. It also provides methods to import xseries capacity data from XML or CSV file and also ability to store xseries capacity data into persistence. XSeriesReportServiceImpl uses JPA EntityManager to perform the various persistence and retrieval operations. It also audits persistence operations using the AuditService. \par
Thread-Safety: This class is mutable and hence conditionally thread-safe. The class will function in thread-safe manner when servicing the service methods is done and none of its configuration parameters/attributes are mutated in parallel using the setter methods. Hence this class performs in a thread-safe manner once its configuration is complete and the configuration parameters are not mutated during the servicing of the service methods.\par
\par
\b XSeriesCapacityDataHandler \b0 [class]: \par
XSeriesCapacityDataHandler extends from SAX DefaultHandler. It is used in importCapacityData() method of XSeriesReportServiceImpl when the import data is in XML format as the handler for callbacks from the SAX parsing of the XML file. On receiving callbacks during the sax parsing, it will create and store instance of XSeriesCapacity data from the xml data which can be retrieved from the instance.\par
Thread-Safety: This class is mutable and not thread-safe. However it is created and used as the callback handler by XSeriesReportServiceImpl internally in importCapacityData() method and not shared among threads and hence will function thread-safely.\par
\pard\nowidctlpar\sa120\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b\f1 1.5\tab Component Exception Definitions\f0\par
\pard\nowidctlpar\li720\sa120\f1 IllegalArgumentException\par
\b0 This exception is thrown in various methods if null object is not allowed, or the given string argument is empty or a parameter is invalid [like negative Ids]. Refer to the documentation in the methods in the tcuml file for more details.\par
This is a runtime exception.\f0\par
\cf1\b\f1 NOTE: Empty string means string of zero length or string full of whitespaces.\par
\cf0 XSeriesReportServiceException\par
\b0 XSeriesReportServiceException is the base exception of the component and extends from XSeriesReportServiceException and is thrown to indicate that there is issue in XSeries report generation or import or insert of Xseries capacity data. This exception is thrown from the methods of XSeriesReportService and its implementation to indicate issues in servicing the request. Specific sub-classes of this exception in this component are defined to handle specific exception cases in servicing the requests.\par
This is a checked exception.\par
Thread-Safety: This class extends from a thread-safe base class and does not define state of its own and neither modifies the super class state and hence is thread-safe.\par
\par
\b XSeriesCapacityDataParsingException\f0\par
\b0\f1 XSeriesCapacityDataParsingException extends from XSeriesReportServiceException and is thrown by the importCapacityData() method of XSeriesReportService to indicate that the capacity data coming from the input stream is in invalid or incorrect format or there are any I/O errors in reading the data from the stream.\par
This is a checked exception.\par
Thread-Safety: This class extends from a thread-safe base class and does not define state of its own and neither modifies the super class state and hence is thread-safe.\par
\pard\nowidctlpar\sa120\par
\pard\nowidctlpar\li720\sa120\b XSeriesCapacityReportGenerationException\f0\par
\b0\f1 XSeriesCapacityReportGenerationException extends from XSeriesReportServiceException and is thrown by the getSummaryReport(), getDetailedReport(), generateSummaryReport() and generateDetailedReport() methods of the XSeriesReportService class to indicate issue in generation and output/store/write of the report data.\par
This is a checked exception.\par
Thread-Safety: This class extends from a thread-safe base class and does not define state of its own and neither modifies the super class state and hence is thread-safe.\par
\pard\nowidctlpar\sa120\f0\par
\pard\nowidctlpar\li720\sa120\b\f1 ConfigurationException [\b0 not defined in this component but used from DST Capacity Tools Entities and Exceptions Component\b ]\par
\b0 Used from DST Capacity Tools Entities and Exceptions Component and thrown in the methods of this component to indicate issues with configuration data for the service.\par
This is a runtime exception.\par
\b\par
CapacityToolServiceException [\b0 not defined in this component but used from DST Capacity Tools Entities and Exceptions Component\b ]\par
\b0 Used from DST Capacity Tools Entities and Exceptions Component and acts as a base class for the exception classes defined in this component.\par
This is a checked exception.\par
\b\par
PersistenceException [\b0 not defined in this component but used from DST Capacity Tools Entities and Exceptions Component\b ]\f0\par
\b0\f1 Used from DST Capacity Tools Entities and Exceptions Component and thrown in the service methods of this component to indicate JPA persistence issues.\par
This is a checked exception.\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 1.6\tab Thread Safety\par
\pard\nowidctlpar\li720\sa120\b0 This component is conditionally thread-safe. As required by the ADS, this component follows the approach of providing thread-safety as long as the configuration data for the service class implementation is not changed during the execution of the service methods.\par
Please refer to each of the class documentation to see in detail as to how the service classes function in this conditional thread-safe manner.\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx360\b 2.\tab Environment Requirements\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0 2.1\tab Environment\par
\pard\nowidctlpar\li720\sa120\b0 Java 1.6 \par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 2.2\tab TopCoder Software Components\f0\par
\pard\nowidctlpar\fi800\sa120\qj\b0\f3\fs22 DST Capacity Tool Entities and Exceptions 1.0 [Custom component]\par
DST Capacity Tool Backend Miscellaneous Services 1.0 [Custom component]\par
No other Topcoder Generic components are used\f1\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 2.3\tab Third Party Components\par
\pard\fi800\b0     Log4j 1.2.14 : {\field{\*\fldinst{HYPERLINK "http://logging.apache.org/log4j/"}}{\fldrslt{\ul\cf4 http://logging.apache.org/log4j/}}}\f1\fs20\par
    Spring 3.0.3: {\field{\*\fldinst{HYPERLINK "http://www.springsource.org/"}}{\fldrslt{\ul\cf4 http://www.springsource.org/}}}\f1\fs20\par
    Open JPA 2.0.1: {\field{\*\fldinst{HYPERLINK "http://openjpa.apache.org/"}}{\fldrslt{\ul\cf4 http://openjpa.apache.org/}}}\f1\fs20\par
    Open CSV 2.3: {\field{\*\fldinst{HYPERLINK "http://opencsv.sourceforge.net/"}}{\fldrslt{\ul\cf4 http://opencsv.sourceforge.net/}}}\f1\fs20\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx360\b 3.\tab Installation and Configuration\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0 3.1\tab Package Name\par
\pard\nowidctlpar\li720\sa120\sl240\slmult0\b0 com.ibm.dst.capacity.services  [Main package which defines the XSeriesReportService and the exceptions in this component].\f0\par
\f1 com.ibm.dst.capacity.services.impl   [Contains the implementation of the service in this component and the classes used by them]\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 3.2\tab Configuration Parameters\f0\par
\pard\nowidctlpar\li720\b0\fs24 The configuration parameter\rquote s for the service in this component is done using Spring IOC. The following are the configuration properties for each of the service implementation and controller classes.\par
\par
\ul\b\f1\fs20 XSeriesReportServiceImpl\ulnone\par
\b0\par
\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clcbpat7\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clcbpat7\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar\b Property Name\cell Expected Property Value\cell\row\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar\b0\cell\cell\row\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar entityManager\cell An instance of JPA javax.persistence.EntityManager. \par
Should not be null and should not be closed.\par
This is a required property.\cell\row\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar Logger\cell An instance of Log4j Logger to be used for performing logging. It can be null, indicating no logging needs to be performed in the service.\par
This is an optional property\cell\row\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar auditService\cell An instance of AuditService used for performing the audit of XSeriesCapacity entities being imported / inserted.\par
\par
It cannot be null. \par
This is a required property.\cell\row\trowd\trgaph108\trleft612\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx3608\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx6770\pard\intbl\nowidctlpar lookupDataService\cell An instance of LookupDataService used for fetching the needed lookup entities as a part of imported of capacity data.\par
\par
It cannot be null. \par
This is a required property.\cell\row\pard\nowidctlpar\ul\b\par
\pard\nowidctlpar\li720\par
\page Sample Spring Configuration File\par
\ulnone\par
\trowd\trgaph108\trleft-108\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b0 <?xml version="1.0" encoding="UTF-8"?>\par
\pard\intbl <beans xmlns="http://www.springframework.org/schema/beans"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://www.springframework.org/schema/beans {\field{\*\fldinst{HYPERLINK "http://www.springframework.org/schema/beans/spring-beans.xsd"}}{\fldrslt{\ul\cf4 http://www.springframework.org/schema/beans/spring-beans.xsd}}}\f1\fs20 ">\par
\par
<!-- Note: Important, this is just a sample configuration file and is not fully complete.\par
Some of referenced Bean definitions passed as parameter come from other components whose implementation class is not known and hence those reference are mentioned but will not work. -->\par
<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean" >\par
\tab <property name="persistenceUnitName" value="dst_xseries_report_service"/>\par
</bean>\par
<bean id="auditService" class="com.ibm.dst.capacity.services.impl.AuditServiceImpl"/>\par
<bean id="lookupDataService" class="com.ibm.dst.capacity.services.impl.LookupDataServiceImpl"/>\par
<bean id="xseriesReportService" class="com.ibm.dst.capacity.services.impl.XSeriesReportServiceImpl">         \par
     <property name="auditService" ref="auditService"/>\par
\tab <property name="lookupDataService" ref="lookupDataService"/>\par
</bean>\par
<bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>\par
<!-- For scanning and processing the annotations in the package like PostConstruct, PersistenceContext etc. -->\par
<context:annotation-config/>\par
<context:component-scan base-package="com.ibm.dst.capacity.services" />  \par
<bean class="org.springframework.context.annotation.CommonAnnotationBeanPostProcessor"/>\par
</beans>\cell\row\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b\par
3.3\tab Dependencies Configuration\par
\pard\nowidctlpar\li720\sa120\sl240\slmult0\b0 None\par
\pard\nowidctlpar\sa120\f0\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx360\b\f1 4.\tab Usage Notes\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0 4.1\tab Required steps to test the component\par
\pard\nowidctlpar\fi-420\li1140\sa120\tx1140\lang2052\b0\f6\'d8\lang1033\f7\tab\f1 Extract the component distribution.\par
\pard\nowidctlpar\fi-420\li1140\sa120\lang2052\f6\'d8\lang1033\f7\tab\f1 Follow \cf4\ul Dependencies Configuration\cf0\ulnone .\par
\lang2052\f6\'d8\lang1033\f7\tab\f1 Execute \lquote ant test\rquote  within the directory that the distribution was extracted to.\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 4.2\tab Required steps to use the component\par
\pard\nowidctlpar\li720\sa120\sl240\slmult0\b0 Configure the component through Spring configuration file [a sample one provided could be referred though it is not complete].\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx0\b 4.3\tab Demo\par
\cf1 We assume the Spring configuration file provided in the distribution is used for the configuring this component for this demo.\par
\pard\keepn\nowidctlpar\sb120\sa60\sl240\slmult0\tx0\cf0\b0\i XSeriesReportService creation & use\par
\trowd\trgaph108\trleft-108\trbrdrl\brdrs\brdrw10 \trbrdrt\brdrs\brdrw10 \trbrdrr\brdrs\brdrw10 \trbrdrb\brdrs\brdrw10 \trpaddl108\trpaddr108\trpaddfl3\trpaddfr3
\clbrdrl\brdrw10\brdrs\clbrdrt\brdrw10\brdrs\clbrdrr\brdrw10\brdrs\clbrdrb\brdrw10\brdrs \cellx9468\pard\intbl\nowidctlpar\fi-360\li1080\cf5\i0\f4\fs18 // Creating the instances from the configured Spring configuration file.\par
// Initializing the Springs Bean factory\par
\cf6\par
ApplicationContext context = new ClassPathXmlApplicationContext(\par
\tab\tab\tab\tab "beans.xml");\par
BeanFactory factory = context;\par
\par
\cf5 // Fetch the bean instance for each of the Services\par
\cf6 XSeriesReportService xSeriesReportService = (XSeriesReportService)\cf0\lang16393\f3\fs22  \cf6\lang1033\f4\fs18 factory\par
\tab\tab\tab\tab .getBean("xseriesReportService");\par
\pard\intbl\nowidctlpar\par
\pard\intbl\nowidctlpar\fi-360\li1080\par
\cf5 // Using the methods of XSeries Definition Service\par
// Fetching the XSeries Summary Report for page 2 with page size 10.\par
\pard\intbl\nowidctlpar\cf6\par
\pard\intbl\nowidctlpar\fi480\li240 XSeriesSummaryReportCriteria summaryReportCriteria = \'85.. // Create the needed instance of XSeriesSummaryReportCriteria as per the criteria needed.\par
\par
PagedResult<XSeriesSummaryReportEntry> summaryReport = xSeriesReportService.getSummaryReport(summaryReportCriteria, 2, 10)\par
\par
\pard\intbl\nowidctlpar\cf5\par
      // Generating and storing the contents of Summary Report to output stream in \par
      // XML and CSV format.\par
\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 ByteArrayOutputStream stream = new ByteArrayOutputStream();\par
\par
xSeriesReportService.generateSummaryReport(summaryReportCriteria, ReportFormat.XML, stream); // stream contents will now have report contents in XML format\par
\pard\intbl\nowidctlpar\cf5\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 xSeriesReportService.generateSummaryReport(summaryReportCriteria, ReportFormat.CSV, stream); // stream contents will now have report contents in CSV format\par
\pard\intbl\nowidctlpar\cf5\par
\par
\par
      // Fetching the XSeries Detailed Report for page 1 with page size 20.\par
\cf6\par
\pard\intbl\nowidctlpar\fi480\li240 XSeriesDetailedReportCriteria detailedReportCriteria = \'85.. // Create the needed instance of XSeriesDetailedReportCriteria as per the criteria needed.\par
\par
PagedResult<XSeriesCapacity> detailReport = xSeriesReportService.getDetailedReport(detailedReportCriteria, 1, 20)\par
\pard\intbl\nowidctlpar\fi-360\li1080\cf5\par
\par
\pard\intbl\nowidctlpar       // Generating and storing the contents of Detailed Report to output stream in \par
      // XML and CSV format.\par
\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 ByteArrayOutputStream stream = new ByteArrayOutputStream();\par
\par
xSeriesReportService.generateDetailedReport(detailedReportCriteria, ReportFormat.XML, stream); // stream contents will now have report contents in XML format\par
\pard\intbl\nowidctlpar\cf5\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 xSeriesReportService.generateDetailedReport(detailedReportCriteria, ReportFormat.CSV, stream); // stream contents will now have report contents in CSV format\par
\par
\par
\pard\intbl\nowidctlpar\fi-360\li1080\cf5 // Let us assume that the files XSeriesCapacityData.csv and XSeriesCapacotyData.xml \par
// have xseries capacity data in csv and xml formats respectively as mentioned \par
// in section 1.3.4 and 1.3.7\par
// Importing these data in the files\par
\pard\intbl\nowidctlpar\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 xSeriesReportService.importCapacityData( new FileInputStream ( \ldblquote XSeriesCapacityData.csv\rdblquote , \ldblquote topcoder\rdblquote ); // Will insert data from CSV file.\par
\pard\intbl\nowidctlpar\cf5\par
\pard\intbl\nowidctlpar\fi480\li240\cf6 xSeriesReportService.importCapacityData( new FileInputStream ( \ldblquote XSeriesCapacityData.xml\rdblquote , \ldblquote topcoder\rdblquote ); // Will insert data from XML file.\par
\pard\intbl\nowidctlpar\par
\par
\pard\intbl\nowidctlpar\fi-360\li1080\cf5 // Importing XSeries Capacity data directly.\par
\pard\intbl\nowidctlpar\par
\pard\intbl\nowidctlpar\fi-360\li1080\cf6 List<XSeriesCapacity> capacityData = \'85.. // List of capacity data.\par
\par
xSeriesReportService.insertCapacityData( capacityData \ldblquote topcoder\rdblquote );\par
\par
\par
\cf0\i\f0\fs20\cell\row\pard\nowidctlpar\fi-358\li358\cf6\i0\f4\fs18\par
\pard\keepn\nowidctlpar\sb120\sa120\sl240\slmult0\tx360\cf0\b\f1\fs20 5.\tab Future Enhancements\par
\pard\nowidctlpar\li720\sa120\sl240\slmult0\b0 None.\f0\par
\pard\nowidctlpar\fs24\par
}
 